Skip to main content

Organisation Management

Organisation management is structured as a two-tier model, consisting of:

  • Root Organisations
  • Sub-Organisations

Each tier allows multiple users to be affiliated, with specific access and operational rules.

Hierarchical Structure​

The following structure illustrates how root and sub-organisations are managed:

image

Key Points​

  • Root Organisations can have multiple sub-organisations.
  • Sub-Organisations cannot have further sub-organisations.
  • A user can be affiliated with one or more root or sub-organisations.

Root Organisation Users:​

  • Can view all users within their root organisation as well as within any sub-organisations.
  • Have permissions to perform operations on both their organisation and associated sub-organisations.

Sub-Organisation Users:​

  • Only see and manage data within their assigned sub-organisation.
  • Cannot access or view the parent root organisation.

Example Scenario​

To clarify the permissions:

  • Example A: A user in the root organisation “ABC Holdings” can access and operate on “ABC Holdings - Child 1” and “ABC Holdings - Child 2” (sub-organisations).
  • Example B: A user in “ABC Holdings - Child 1” will not see or interact with “ABC Holdings” or other sub-organisations like “ABC Holdings - Child 2.”

This structure uses Role-Based Access Control (RBAC) to manage permissions within each tier, ensuring that users can only access and operate within the scope of their assigned organisation.

Creating an Organisation​

To create a root organisation, call the create organisation endpoint with the following parameters:

Endpoint:​

POST {{base_url}}/api/organisations

Request Payload:​

{
  "name": "ABC Holdings",
  "type": "computer_services",
  "company_registered_date": "2020-11-01T00:00:00",
  "address": "34 Webings Road",
  "email": "hello@abc.com",
  "phone": "1238129038290",
  "country_code": "ae"
}

Sample Response:​

{
  "id": "2e8ccd2b-f83f-4fe8-b845-c54ab7808715",
  "name": "ABC Holdings",
  "type": "computer_services",
  "company_registered_date": "2020-10-31T16:00:00.000Z",
  "address": "34 Webings Road",
  "email": "hello@abc.com",
  "phone": "1238129038290",
  "country_code": "ae",
  "parent_organisation_id": null,
  "created_at": "2024-05-28T16:09:33.584Z",
  "updated_at": "2024-05-28T16:09:33.584Z",
  "deleted_at": null
}

Creating a Sub-Organisation​

To create a sub-organisation within an existing root organisation, use the following endpoint and payload:

Endpoint:​

POST {{base_url}}/api/organisations/{{organisation_id}}/suborganisations

Request Payload:​

{
  "name": "ABC Holdings - Child",
  "type": "computer_services",
  "company_registered_date": "2020-11-01T00:00:00",
  "address": "34 Webings Road",
  "email": "hello@abc.com",
  "phone": "1238129038290",
  "country_code": "ae",
  "parent_organisation_id": "<parent_organisation_id>"
}

Sample Response:​

{
  "id": "6fe8ccd2b-f83f-4fe8-b845-c54ab7808715",
  "name": "ABC Holdings - Child",
  "type": "computer_services",
  "company_registered_date": "2020-11-01T00:00:00.000Z",
  "address": "34 Webings Road",
  "email": "hello@abc.com",
  "phone": "1238129038290",
  "country_code": "ae",
  "parent_organisation_id": "2e8ccd2b-f83f-4fe8-b845-c54ab7808715",
  "created_at": "2024-05-28T16:09:33.584Z",
  "updated_at": "2024-05-28T16:09:33.584Z",
  "deleted_at": null
}

Frontend User Interface​

Create Organisation​

To create a new company (root organisation), the UI provides the following option:

image

Select Organisation​

To view or select a company, use the following interface:

image